Add AGENTS.md and copilot-setup-steps workflow by Copilot · Pull Request #380 · executablebooks/markdown-it-py

Copilot · 2026-01-19T23:34:13Z

Adds AI coding agent documentation and GitHub Actions workflow for environment setup, following the pattern established in MyST-Parser.

Files Added

AGENTS.md: Comprehensive guide covering project architecture (token stream-based parser with three-stage pipeline: core→block→inline), development workflows (tox-based testing/docs/benchmarking), code style (Ruff/Mypy strict), testing patterns (pytest + CommonMark spec compliance), and common operations (adding parsing rules, creating plugins, customizing renderers)
.github/workflows/copilot-setup-steps.yml: Environment setup workflow that installs Python 3.11, uv, pre-commit/pre-commit-uv, and tox/tox-uv on workflow_dispatch, push, or PR events affecting the workflow file

Key Sections in AGENTS.md

Repository structure reflecting actual layout (markdown_it/, tests/, docs/, benchmarking/)
Architecture details: parser chains (core/block/inline), token stream vs AST approach, Ruler class for rule management
Development commands: tox -e py311, tox -e docs-clean, tox -e py311-bench-core, tox -e profile, tox -e fuzz
Common patterns with code examples for adding rules, creating plugins, and customizing rendering
Debugging techniques: token stream inspection, rule enable/disable, CLI usage

Example debugging pattern documented:

# See the token stream
tokens = md.parse("# Heading\n\nParagraph")
for token in tokens:
    print(f"{token.type} | {token.tag} | {token.content}")

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

https://api.github.com/repos/actions/setup-python/releases
- Triggering command: /usr/bin/curl curl -s REDACTED (http block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Overview

Add an AGENTS.md file and .github/workflows/copilot-setup-steps.yml to the markdown-it-py repository, following the pattern established in the MyST-Parser repository.

Files to Create

1. AGENTS.md

Create an AGENTS.md file in the repository root with guidance for AI coding agents. Use the AGENTS.md from MyST-Parser as a template, but adapt it for markdown-it-py:

Project Overview section should describe:

markdown-it-py is a Python port of markdown-it (JavaScript)
It's a Markdown parser following the CommonMark spec
Configurable syntax with support for plugins
High performance

Repository Structure section should reflect the actual structure:

pyproject.toml          # Project configuration and dependencies (flit)
tox.ini                 # Tox test environment configuration

markdown_it/            # Main source code
├── __init__.py         # Package init
├── main.py             # MarkdownIt main class
├── token.py            # Token dataclass
├── ruler.py            # Ruler class for managing rules
├── tree.py             # SyntaxTreeNode for AST representation
├── renderer.py         # RendererHTML and RendererProtocol
├── parser_core.py      # ParserCore - top-level rules executor
├── parser_block.py     # ParserBlock - block-level tokenizer
├── parser_inline.py    # ParserInline - inline tokenizer
├── utils.py            # Utility types (OptionsType, PresetType, etc.)
├── common/             # Common utilities
├── helpers/            # Helper functions
├── presets/            # Configuration presets (commonmark, gfm-like, zero, etc.)
├── rules_core/         # Core parsing rules
├── rules_block/        # Block-level parsing rules
├── rules_inline/       # Inline parsing rules
├── cli/                # Command-line interface
└── py.typed            # PEP 561 marker

tests/                  # Test suite
├── test_api/           # API tests
├── test_cmark_spec/    # CommonMark spec compliance tests
├── test_port/          # Port-specific tests
├── test_tree/          # SyntaxTreeNode tests
├── fuzz/               # Fuzzing tests for OSS-Fuzz
├── test_cli.py         # CLI tests
├── test_linkify.py     # Linkify tests
└── test_tree.py        # Tree tests

docs/                   # Documentation source
├── conf.py             # Sphinx configuration
├── index.md            # Documentation index
├── architecture.md     # Design principles
├── using.md            # Usage guide
├── plugins.md          # Plugin documentation
├── contributing.md     # Contributing guide
├── performance.md      # Performance benchmarks
└── security.md         # Security considerations

benchmarking/           # Performance benchmarking
scripts/                # Utility scripts

Development Commands section based on tox.ini:

# Run all tests
tox

# Run tests with specific Python version
tox -e py311

# Run tests with plugins
tox -e py311-plugins

# Build docs (clean)
tox -e docs-clean

# Build docs (incremental)
tox -e docs-update

# Run benchmarks
tox -e py311-bench-core
tox -e py311-bench-packages

# Run profiler
tox -e profile

# Run fuzzer
tox -e fuzz path/to/testcase

Code Style Guidelines based on pyproject.toml:

Formatter/Linter: Ruff (configured in pyproject.toml)
Type Checking: Mypy with strict settings
Pre-commit hooks for consistent code style

Architecture Overview based on docs/architecture.md:

Parsing pipeline: Markdown → Tokens → HTML
Three nested chains: core, block, inline
Token stream representation (not AST by default)
Ruler class for managing rules
Renderer for output generation

Include sections for:

Testing guidelines (pytest, pytest-regressions, CommonMark spec tests, fuzzing)
Commit message format (same as MyST-Parser)
PR requirements
Key files
Debugging tips
Common patterns (adding rules, creating plugins)
Reference documentation links

2. .github/workflows/copilot-setup-steps.yml

Create a Copilot setup workflow similar to MyST-Parser's:

name: Copilot Setup Steps

on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest

    permissions:
      contents: read

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: "3.11"
        cache: pip

    - name: Install uv
      run: pip install uv

    - name: Install pre-commit and pre-commit-uv
      run: pip install pre-commit pre-commit-uv

    - name: Install tox and tox-uv
      run: pip install tox tox-uv

References

MyST-Parser AGENTS.md: https://github.com/executablebooks/MyST-Parser/blob/master/AGENTS.md
MyST-Parser copilot-setup-steps.yml: https://github.com/executablebooks/MyST-Parser/blob/master/.github/workflows/copilot-setup-steps.yml
markdown...

This pull request was created from Copilot chat.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: chrisjsewell <2997570+chrisjsewell@users.noreply.github.com>

codecov · 2026-02-18T07:59:24Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.80%. Comparing base (49043e4) to head (ea7d980).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #380   +/-   ##
=======================================
  Coverage   95.80%   95.80%           
=======================================
  Files          64       64           
  Lines        3455     3455           
=======================================
  Hits         3310     3310           
  Misses        145      145

Flag	Coverage Δ
pytests	`95.80% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Initial plan

c09df1a

Copilot AI assigned Copilot and chrisjsewell Jan 19, 2026

Copilot started work on behalf of chrisjsewell January 19, 2026 23:34 View session

Copilot AI and others added 2 commits January 19, 2026 23:38

📚 DOCS: Add AGENTS.md and copilot-setup-steps.yml workflow

9193362

Co-authored-by: chrisjsewell <2997570+chrisjsewell@users.noreply.github.com>

👌 IMPROVE: Add tox-uv note to AGENTS.md

ea7d980

Co-authored-by: chrisjsewell <2997570+chrisjsewell@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add AGENTS.md and copilot workflow steps~~ Add AGENTS.md and copilot-setup-steps workflow Jan 19, 2026

Copilot finished work on behalf of chrisjsewell January 19, 2026 23:43

Copilot AI requested a review from chrisjsewell January 19, 2026 23:43

chrisjsewell marked this pull request as ready for review January 20, 2026 00:31

chrisjsewell approved these changes Jan 20, 2026

View reviewed changes

chrisjsewell approved these changes Feb 18, 2026

View reviewed changes

chrisjsewell merged commit 2f6ae10 into master Feb 18, 2026
16 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add AGENTS.md and copilot-setup-steps workflow#380

Add AGENTS.md and copilot-setup-steps workflow#380
chrisjsewell merged 3 commits intomasterfrom
copilot/add-agents-md-and-workflow-steps

Copilot AI commented Jan 19, 2026 •

edited

Loading

Uh oh!

codecov bot commented Feb 18, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

Copilot AI commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Files Added

Key Sections in AGENTS.md

I tried to connect to the following addresses, but was blocked by firewall rules:

Overview

Files to Create

1. AGENTS.md

2. .github/workflows/copilot-setup-steps.yml

References

Uh oh!

codecov bot commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Copilot AI commented Jan 19, 2026 •

edited

Loading

codecov bot commented Feb 18, 2026 •

edited

Loading